/*=============================================================================

  Library: HMPBundleFrame

  Copyright (c) German Cancer Research Center,
    Division of Medical and Biological Informatics

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.

=============================================================================*/

#ifndef PLUGINEVENT_H
#define PLUGINEVENT_H

#include <QSharedDataPointer>
#include <QSharedPointer>
#include <QMetaType>

#include "hmpbundleframe_global.h"


class IBundle;
class PluginEventData;

/**
 * \ingroup BundleFramework
 *
 * An event from the Framework describing a plugin lifecycle change.
 * <p>
 * <code>BundleEvent</code> objects are delivered to slots connected
 * via BundleContext::connectPluginListener() when a change
 * occurs in a plugins's lifecycle. A type code is used to identify
 * the event type for future extendability.
 *
 * @see BundleContext#connectPluginListener
 */
class HMPBUNDLEFRAMESHARED_EXPORT BundleEvent
{

  QSharedDataPointer<PluginEventData> d;

public:

  enum Type {
    /**
     * The plugin has been installed.
     *
     * @see BundleContext::installBundle(const QString&)
     */
    INSTALLED,

    /**
     * The plugin has been started.
     * <p>
     * The plugin's
     * \link BundleActivator::start(BundleContext*) BundleActivator start\endlink method
     * has been executed.
     *
     * @see Bundle::start()
     */
    STARTED,

    /**
     * The plugin has been stopped.
     * <p>
     * The plugin's
     * \link BundleActivator::stop(BundleContext*) BundleActivator stop\endlink method
     * has been executed.
     *
     * @see Bundle::stop()
     */
    STOPPED,

    /**
     * The plugin has been updated.
     *
     * @see Bundle::update()
     */
    UPDATED,

    /**
     * The plugin has been uninstalled.
     *
     * @see Bundle::uninstall()
     */
    UNINSTALLED,

    /**
     * The plugin has been resolved.
     *
     * @see Bundle::RESOLVED
     */
    RESOLVED,

    /**
     * The plugin has been unresolved.
     *
     * @see Bundle::INSTALLED
     */
    UNRESOLVED,

    /**
     * The plugin is about to be activated.
     * <p>
     * The plugin's
     * \link BundleActivator::start(BundleContext*) BundleActivator start\endlink method
     * is about to be called. This
     * event is only delivered to synchronuous slots, which have been registered with
     * Qt::DirectConnection or Qt::BlockingQueuedConnection in BundleContext::connectPluginListener().
     *
     * @see Bundle::start()
     */
    STARTING,

    /**
     * The plugin is about to deactivated.
     * <p>
     * The plugin's
     * \link BundleActivator::stop(BundleContext*) BundleActivator stop\endlink method
     * is about to be called. This
     * event is only delivered to synchronuous slots, which have been registered with
     * Qt::DirectConnection or Qt::BlockingQueuedConnection in BundleContext::connectPluginListener().
     *
     * @see Bundle::stop()
     */
    STOPPING,

    /**
     * The plugin will be lazily activated.
     * <p>
     * The plugin has a \link BundleConstants::ACTIVATION_LAZY lazy activation policy\endlink
     * and is waiting to be activated. It is now in the
     * \link Bundle::STARTING STARTING\endlink state and has a valid
     * <code>BundleContext</code>. This
     * event is only delivered to synchronuous slots, which have been registered with
     * Qt::DirectConnection or Qt::BlockingQueuedConnection in BundleContext::connectPluginListener().
     */
    LAZY_ACTIVATION
  };

  /**
   * Default constructor for use with the Qt meta object system.
   */
  BundleEvent();

  ~BundleEvent();

  /**
   * Can be used to check if this BundleEvent instance is valid,
   * or if it has been constructed using the default constructor.
   *
   * @return <code>true</code> if this event object is valid,
   *         <code>false</code> otherwise.
   */
  bool isNull() const;

  /**
   * Creates a plugin event of the specified type.
   *
   * @param type The event type.
   * @param plugin The plugin which had a lifecycle change.
   */
  BundleEvent(Type type, QSharedPointer<IBundle> plugin);

  BundleEvent(const BundleEvent& other);

  BundleEvent& operator=(const BundleEvent& other);

  /**
   * Returns the plugin which had a lifecycle change.
   *
   * @return The plugin that had a change occur in its lifecycle.
   */
  QSharedPointer<IBundle> getPlugin() const;

  /**
   * Returns the type of lifecyle event. The type values are:
   * <ul>
   * <li>{@link #INSTALLED}
   * <li>{@link #RESOLVED}
   * <li>{@link #LAZY_ACTIVATION}
   * <li>{@link #STARTING}
   * <li>{@link #STARTED}
   * <li>{@link #STOPPING}
   * <li>{@link #STOPPED}
   * <li>{@link #UPDATED}
   * <li>{@link #UNRESOLVED}
   * <li>{@link #UNINSTALLED}
   * </ul>
   *
   * @return The type of lifecycle event.
   */
  Type getType() const;

};

Q_DECLARE_METATYPE(BundleEvent)

/**
 * \ingroup BundleFramework
 * @{
 */
HMPBUNDLEFRAMESHARED_EXPORT QDebug operator<<(QDebug debug, BundleEvent::Type eventType);
HMPBUNDLEFRAMESHARED_EXPORT QDebug operator<<(QDebug debug, const BundleEvent& event);
/** @}*/

#endif // PLUGINEVENT_H
